Skip to content

Conversation

@OscarArroyoVega
Copy link
Member

🏗️ Refactor: Agent-Based Neo4j Architecture

Major architectural refactor migrating from PostgreSQL RAG to agent-based Neo4j architecture.

Changes

  • Database: PostgreSQL → Neo4j
  • Retriever: Complete rewrite with agent-based architecture (Orchestrator, DBQueryAgent, SafetyGuard)
  • Pusher: Pusher service for event ingestion
  • Legacy: All old services moved to legacy/ folder

Breaking Changes

  • Requires Neo4j database (no longer PostgreSQL)
  • New environment variables: NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD
  • API endpoints may have changed

Benefits

  • Better query accuracy through agent-based generation
  • Improved safety with dedicated guardrails
  • Scalable architecture for future enhancements

…in database folder for coherence

Data files should not be tracked per .gitignore policy.
Files remain locally but are no longer in git.
Move old frontend, parser, scraper, and retriever services to legacy/
folder as part of architectural refactor. New agent-based retriever and
pusher services replace the legacy implementation.

- Migrate legacy services to legacy/services/
- Move legacy docker-compose and Makefile to legacy/
- Preserve database schemas in legacy/database/
- New services use agent-based architecture
Preserve old implementation for reference:
- services/frontend/ → legacy/services/frontend/
- services/parser/ → legacy/services/parser/
- services/scraper/ → legacy/services/scraper/
- services/retriever/ (old) → legacy/services/retriever/
- docker-compose.yml → legacy/docker-compose.yml
- docker-compose.override.yml → legacy/docker-compose.override.yml
- Makefile → legacy/Makefile
- database/ → legacy/database/
Add Neo4j client module to retriever service:
- services/retriever/agent/clients/neo4j_client.py
- Update config.py with Neo4j settings
Implement core agent architecture:
- Orchestrator: routes queries and manages conversation flow
- DBQueryAgent: generates and executes Neo4j Cypher queries
- SafetyGuard: validates queries and enforces safety constraints
Complete retriever service implementation:
- FastAPI endpoints for chat and query
- Service configuration and Dockerfile
- Dependencies (pyproject.toml, uv.lock)
New service for multimodal event submission:
- Basic API structure with health endpoint
- Configuration and Dockerfile
- Observability integration
Update infrastructure to support new services:
- docker-compose.yml: retriever and pusher services
- docker-compose.override.yml: development configuration
- Makefile: new service commands
- Dev-container: update dev-container
@OscarArroyoVega OscarArroyoVega self-assigned this Dec 31, 2025
@OscarArroyoVega OscarArroyoVega merged commit e33267e into main Dec 31, 2025
2 checks passed
@OscarArroyoVega OscarArroyoVega deleted the refactor/agentic-architecture branch December 31, 2025 17:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants